/******************************************************************************
 * Copyright (C) 2024 Ant IOT, Inc.(Gmbh) or its affiliates.
 * 
 * All Rights Reserved.
 * 
 * @file bsp_led_driver.h
 * 
 * @par dependencies 
 * - stdio.h
 * - stdint.h
 * - stdbool.h
 * 
 * @author ZCH | R&D Dept. | Ant IOT 蚂蚁物联
 * 
 * @brief Provide the HAL APIs of LEDs and corresponding opetions.
 * 
 * Processing flow:
 * 
 * call directly.
 * 
 * @version V1.0 2025-04-09
 *
 * @note 1 tab == 4 spaces!
 * 
 *****************************************************************************/
#ifndef __BSP_LED_DRIVER_H__  //Avoid repeated including same files later
#define __BSP_LED_DRIVER_H__

//******************************** Includes *********************************//
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>

//******************************** Includes *********************************//


//******************************** Defines **********************************//
#define INITED            1          /* LED is inited                        */
#define NOT_INITED        0          /* LED is not inited                    */
    
#define OS_SUPPORT        1          /* OS_SUPPORT depending on OS avaliable */ 
#define DEBUG                        /* Enable DEBUG                         */
#define DEBUG_OUT(X)      printf(X)  /* DEBUG output info indicate status    */

typedef enum
{
    LED_OK             = 0,      /* LED Operation completed successfully.    */
    LED_ERROR          = 1,      /* LED Run-time error without case matched. */
    LED_ERRORTIMEOUT   = 2,      /* LED Operation failed with timeout.       */
    LED_ERRORRESOURCE  = 3,      /* LED Resource not available.              */
    LED_ERRORPARAMETER = 4,      /* LED Paramter error.                      */
    LED_ERRORNOMEMORY  = 5,      /* LED Out of memory.                       */
    LED_ERRORISR       = 6,      /* LED Not allowed in ISR context.          */
    LED_RESERVED       = 0xFF,   /* LED Reserved.                            */
} led_status_t;

typedef enum
{
    PROPORTION_1_3    = 0,       /* LED Operation completed successfully.    */
    PROPORTION_1_2    = 1,       /* LED Operation completed successfully.    */
    PROPORTION_1_1    = 2,       /* LED Operation completed successfully.    */
    PROPORTION_x_x    = 0xFF     /* LED Operation completed successfully.    */
} proportion_t;



typedef struct
{
    /**
     * zch: 为什么不设计成 pf_gpio_set / pf_gpio_reset， 因为对于 led 类来说, 根本
     *      不需要知道是高电平点亮 LED，还是低电平点亮 LED, 也根本不用关心 是 GPIO 
     *      点亮 LED 还是通过什么方式。
     */
    led_status_t (*pf_led_on)  (void);  /* LED Reserved.                     */
    led_status_t (*pf_led_off) (void);  /* LED Reserved.                     */
} led_operations_t;

typedef struct
{
    led_status_t (*pf_get_time_ms) ( uint32_t * const );
} time_base_ms_t;

#ifdef OS_SUPPORT
    /**
     * zch: 对于裸机来说是需要这个 Delay 函数, 因此使用
     *      OS_SUPPORT 宏进行控制。
     * 
     */
typedef struct
{
    led_status_t (*pf_os_delay_ms) ( const   uint32_t );
    
} os_delay_t;
#endif // OS_SUPPORT

typedef led_status_t (*pf_led_control)(
                                    uint32_t ,            //     Cycle_time[ms]
                                    uint32_t ,            // blink_times[times]
                                    proportion_t          //  propertion_on_off
                                               );

typedef struct
{
    /************ Target of Internal Status *******/
    uint8_t                               is_inited;

    /************ Target of Features **************/
	/* The whole time of                  blink   */
    uint32_t                          cycle_time_ms;

    /* The times of blink                         */
    uint32_t                            blink_times;

    /* The relationship of light on and off time  */
    proportion_t                  proportion_on_off;
    
    /************ Target of IOs needed ************/
    /* The interfaces from Core layer             */
    led_operations_t               *p_led_opes_inst;
    time_base_ms_t                  *p_time_base_ms;
#ifdef OS_SUPPORT
    /**
     * zch: 对于裸机来说是需要这个 Delay 函数, 因此使用
     *      OS_SUPPORT 宏进行控制。
     * 
     */
    /* The interfaces from Core layer             */
    os_delay_t                      p_os_time_delay;
#endif // OS_SUPPORT

    /************ Target of APIs ******************/
    pf_led_control                pf_led_controller;

}bsp_led_driver_t;

//******************************** Defines **********************************//


//******************************** Declaring ********************************//
/**
 * @brief instantitate the target of bsp_led_driver_t
 *
 * Steps:
 * 1, Adding the Core interface into target of bsp_led_driver.
 * 2, Adding the OS interface into target of bsp_led_driver.
 * 3, Adding the timebase interface into target of bsp_led_driver interface.
 *
 * @param[in] self      : XXXXXXXXXX.
 * @param[in] led_ops   : XXXXXXXXXX.
 * @param[in] os_delay  : XXXXXXXXXX.
 * @param[in] time_base : XXXXXXXXXX.
 * 
 * @return led_status_t : the status of running.
 */

/**
 * zch: 优化点 入参规定好 const 属性, 接口上加限制, 架构师的头文件就是敢写且不怕实现
 *      人员用错。
 * 
 */
led_status_t led_driver_inst (
                                bsp_led_driver_t       * const      self,
                                const led_operations_t * const   led_ops,
#ifdef OS_SUPPORT
                                /**
                                * zch: 对于裸机来说是需要这个 Delay 函数, 因此使用
                                *      OS_SUPPORT 宏进行控制。
                                * 
                                */
                                const os_delay_t       * const  os_delay,
#endif // OS_SUPPORT
                                const time_base_ms_t   * const time_base

);

//******************************** Declaring ********************************//
#endif // End of __BSP_LED_DRIVER_H__ 
